MACD 5/MACD 5.bin/workbench/time/clock1_2/clock.doc

Text File | 1994-05-16 | 12.7 KB | 342 lines

clock 1.2 - A flexible, efficient digital clock with date and memory watching

Copyright © 1994 by Peter Schachte

This is an efficient digital titlebar clock that can also show date,
day of week, free chip/fast/total memory, largest free
chip/fast/either memory block, with full control over formatting, pen
color for various parts of the display, and refresh frequency.  The
clock can also show the local time in a different time zone.  Clock
only updates parts of the display that need updating, so CPU usage is
kept very low.  This program should work under AmigaOS 1.2 and up.



DISCLAIMER

I hereby disclaim all responsibility for any damages caused by this
program.  Use it at your own risk.  It's hard to see what damage could
be be caused by a clock program, but if any is, don't sue me.



DISTRIBUTION

This code is based on Mike Meyer's clock program, though by now very
little of his code remains.  In fact, I've changed the spirit of his
program, which was quite small and simple; now it's (relatively) large
and complex, and probably has altogether too many features.

Nevertheless, here's Mike's original copyright notice:

================================================================
clock - a dumb, digital clock in the upper right-hand corner. Designed
    to be small, not flexible!

Copyright (c) 1986, Mike Meyer

Permission is hereby granted to distribute this program for any purposes
whatsoever, so long as this notice, including the above copyright, is
included with the distribution. Unlike other people, I don't care if you
make money off of this, so long as I get credit for having written it.
================================================================

I likewise hereby grant the right to distribute this program for
any purposes whatsoever, as long as this notice, including my
copyright and Mike's, is included with the distribution.



WHY ANOTHER CLOCK

I know, I know, there are many good clock programs available, why
would I write another one?

I had been using a slightly modified version of Mike Meyer's clock
program since AmigaOS 1.2, and hadn't though much about it, when I
found a copy of Stefan Sticht's public domain Uhr clock on Aminet.  I
really liked the look of and flexibility of it, and promptly replaced
my old clock with it.  But after a week or so I realized that there
seemed to be some interaction between Uhr and Martin Korndörfer's
Magic Menu package, which caused the machine to lock up for about 30
seconds occasionally when a menu was popped up.  Without Uhr running,
this doesn't seem to happen.  I couldn't part with Magic Menus, so I
went back to Mike Meyer's clock.

But by then I was dissatisfied with the boring Topaz font and fixed
display, so I dusted off Mike's clock sources and set to work.  Now,
having put far too many features into this simple program, I'm
releasing it upon the world.  Here are some of the features of this
clock program:

    o It's pretty efficient, only updating parts of the window
      that have changed since the last display, and only actually
      pulling the window to the front when it finds itself
      covered.  Clock's default display, uses about a third to a
      tenth of the machine cycles of Uhr's default display,
      according to xoper.  This despite the fact that clock runs
      at higher priority, keeps itself in front, and shows free
      memory statistics, none of which Uhr does by default.

    o It works under OS >=1.2 (though I've only tested it under
      1.3 and 2.1).

    o It shows available memory and largest available memory
      block, for fast memory, chip memory, or both, in bytes or
      kilobytes.

    o It allows you to organize the clock display into fixed
      segments separated by vertical bars (or nice 3D-look bars
      under OS 2.0 or better).  Each segment will be allocated the
      space it would occupy at its widest, and will be centered in
      that space.  This only matters much for weekday and month
      names.  This makes it easier to find the information of
      interest at a glance.

By the way, none of this should be construed as a criticism of Uhr.
As I said, I really liked Uhr, there were just a few things about it
that didn't suit me.  And I did consult Uhr's sources to help be get
the event loop for this program right.

In fact, Uhr is better than this clock program in the following ways:

    o Clock doesn't support internationalization.  Sorry, you're
      stuck with english month and day names.  I'd like to make it
      use locale.library if it's there, but I don't have the
      includes (I expected to find them in my SAS/C 6.3 package,
      but no such luck).  I may fix this if I get ahold of the
      includes.

    o Clock is three or four times bigger than Uhr.  This is
      because of the code to handle incremental redisplay, and
      because, in order to make it work under pre 2.0 systems,
      I have to include code for things that are in more recent
      libraries.

So the inspiration for this program comes from Stefan Sticht's Uhr,
and the base for the software was Mike Meyer's original Clock program.
Thanks to both of them.



INSTALLATION

Under AmigaOS 2.0 and better, the easiest thing is to drag the clock
icon to your sys:wbstartup drawer.  Under 1.3 and older, you'll need
to drag the clock to some appropriate place, and put a line in your
s:startup-sequence or s:startupII file to launch the clock.  In this
case you might prefer to use the program clock-det, which detaches
itself, so you don't need to run or runback it.  clock-det is
identical to clock, except for detaching itself, and being about 1K
bigger.



CUSTOMIZATION

You can customize clock and clock-det (hereafter, where I write clock,
I mean either program) by passing parameters on the command line, or
by setting up tooltypes on the icon.  If you launch clock from the CLI
or startup script, the tooltypes will be ignored, so you'll have to
use command line parameters.

On the command line, parameters are specified by alternating parameter
names and values, like

    clock PARAM1 VALUE1 PARAM2 VALUE2 ...

In tooltypes, of course, they are specified as

    PARAM1=VALUE1
    PARAM2=VALUE2

Either way, the parameters and possible values are the same.

The parameters you can specify are:

INTERVAL    The time between updates of the clock window, in
        tenths of a second.  Defaults to 10, updating every
        second.  Note that the window is only brought to the
        front every INTERVAL tenths of a second, so making
        this too long will allow your window to be buried for
        that long.

PRIORITY    The priority of the clock process.  Defaults to 1,
        which is just a bit higher than most other things.
        Having a priority greater than 0 makes displaying
        memory statistics more useful, as they get updated
        even while a CPU hog process is running (assuming it
        runs at priority 0 or less).

LEFT        The horizontal position of the clock window.  If the
        number is positive, this is the X coordinate of the
        left edge of the window.  If it is negative, it is the
        pixel offset between the right of the screen and the
        right side of the clock window.  Defaults to the right
        amount of space so that the window lies just to the
        left of the depth/zoom gadgets of a window flush with
        the right side of the screen.  For >=2.0, this means the
        default is -46; for <=1.3, its -52.

TOP        The vertical position of the window.  Again, negative
        numbers are measured between the bottom of the window
        and the bottom of the screen, while positive numbers
        are offsets from the top of the screen.  Default is 0.

BACKGROUND    The pen color to use as the background color of the
        clock.  Defaults to 0, which is the usual window and
        screen background color.  If you use Martin
        Huttenloher's beautiful Magic WB colors, color 6 looks
        quite nice.

PADDING        The number of pixels to leave empty at the left and
        right sides of the clock.  This amount of space is
        also left on either side of a bar (see %| format
        below).  Defaults to 5.

OFFSET        A number of minutes to add to the current local time
        to give the time to show in the clock.  If you want to
        put up a clock showing the current time in Paris or
        Rome, use this offset.  Note that the offset is in
        minutes, and may be positive or negative.  The
        default, of course, is 0.

FORMAT        A format string specifying exactly what to show in the
        clock window.  Format specifiers are introduced by a
        '%' character.  All other characters are shown in the
        clock as is, much like a printf() format string.  Note
        that '\' is not a special character in the format
        string.  The definition of the format string is much
        the same as that use by Uhr, but extended with a few
        new features.  Here's the full set:

        TIME

            %H  hour in 24 hour time, zero-filled
            %q  hour in 24 hour time whitespace-filled
            %I  hour in 12 hour time, zero-filled
            %Q  hour in 12 hour time whitespace-filled
            %M  minute
            %S  second
            %p  "AM" or "PM"
            %r  same as "%I:%M:%S %p"
            %R  same as "%H:%M"
            %T  same as "%H:%M:%S"
            %X  same as "%H:%M:%S"

        DATE

            %y  last two digits of the year, zero filled
            %Y  the full four-digit year
            %b  short version of the month name
            %h  same as %b
            %B  full month name
            %m  month number, zero filled.
            %J  month number, whitespace filled.
            %d  day of the month, zero filled.
            %e  day of the month, whitespace filled.
            %a  short version of the day of the week
            %A  full day of the week
            %w  day of the week, as a digit 1-7
            %j  day of the year, as a number 1-366
            %U  week number, 1-53, with Sunday beginning the week
            %W  week number, 1-53, with Monday beginning the week
            %D  same as "%m/%d/%y"
            %x  same as "%m/%d/%y"
            %c  same as "%a %b %d %H:%M:%S %Y"
            %C  same as "%a %b %e %T %Z %Y"

        MEMORY

            %f  bytes of free FAST memory
            %F  kilobytes of free FAST memory
            %g  bytes of free CHIP memory
            %G  kilobytes of free CHIP memory
            %K  total bytes of free memory
            %k  total kilobytes of free memory
            %o  size of largest block of CHIP memory, in bytes
            %O  size of largest block of CHIP memory, in kilobytes
            %v  size of largest block of FAST memory, in bytes
            %V  size of largest block of FAST memory, in kilobytes
            %z  size of largest block of memory, in bytes
            %Z  size of largest block of memory, in kilobytes

        FORMATTING

            %0  Choose pen 0 for following text
            %1  Choose pen 1 for following text
            %2  Choose pen 2 for following text
            %3  Choose pen 3 for following text
            %4  Choose pen 4 for following text
            %5  Choose pen 5 for following text
            %6  Choose pen 6 for following text
            %7  Choose pen 7 for following text
            %8  Choose pen 8 for following text
            %9  Choose pen 9 for following text
            %|  A top-to-bottom bar separating parts of clock
            %%  A percent sign character
            %n  newline (ignored since clock is only 1 line)
            %t  tab (ignored for now)

        The default format is

            "%2Chip: %1%G%|%2Fast: %1%F%|%e %b %y%|%A%|%q:%M"




SOURCE CODE

I've included the source code and a makefile for use with SAS/C v6.
If you make an interesting improvements to this clock, or if you fix
any bugs, please send me a copy.  If I like it I'll include it in the
next release.



BUGS AND POTENTIAL IMPROVEMENTS

There's one bug I know about.  When you close the active window, and
this makes the clock window the active window, the display is
sometimes corrupted.  I don't know why I don't seem to get an
IDCMP_ACTIVEWINDOW message in this case, but since the clock isn't
notified, it isn't refreshed.  To get it refreshed, all you have to do
is click anywhere, either in another window, or in the screen
background, or in the clock window.  If anyone knows how to fix this,
please let me know.

There may also be an intermittent enforcer hit in there somewhere.  I
thought I had fixed it, but it's happened since then and I haven't
tracked it down yet.  It's very rare, and happens occasionally when
closing another window.  It's only a read hit in page 0, so it's
pretty harmless.  It's certainly never crashed my machine or anything.
Still, if you run enforcer and see the hit, please save it and email
it to me.  Thanks.

As I mentioned above, I'd like to support internationalization using
locale.library.  As soon as I get the include files, I'll do this.
Shouldn't be hard.

I'd like to let users specify their own font.

I'd like the clock to do public screen hopping for users of OS>=2.0,
keeping the clock on the frontmost public screen.  What I plan is to
let users specify a list of screens they wish to allow the clock onto,
and if one of these is frontmost, the clock would move there.



AUTHOR

I welcome bug reports, suggestions, and comments.  I can be contacted
by email at:

    [e-mail]

or by physical mail at

    Peter Schachte
    293 Edward Street
    Brunswick East, Victoria  3057
    Australia